- Special Edition Using Visual Basic Script -

Appendix C - VBScript Coding Conventions

Coding conventions are nothing more than a set of rules pertaining to good programming practice. A computer can understand "spaghetti code" (convoluted, messy code that makes no sense at all to a human who tries to understand it) and other types of gobbledygook that would drive any sane person over the edge. By adhering to some simple guidelines, your code will not only be understandable to the next person who needs to maintain it, but, even you will be able to understand it six months after you wrote it.

These guidelines are based on commonly accepted rules of good programming practice, but they are not carved in stone. Pick what you like, modify what you don't like, and create your own set of rules that you can understand and communicate to others should the need arise. But, by all means, once you've determined which set of rules to use, use them, and use them rigorously and consistently.

Controls

When you create a control using a tool such as the VB IDE, or the ActiveX Control Pad, the control is created with a default name, such as Frame1. While any name can be used, it's good practice to replace the default with a more meaningful name. It's also extremely helpful to use a prefix, so you will know what type of control it is when looking at code it pertains to. For example, Frame1 tells you that the object in question is a Frame control, Options gives you a clue about what the control pertains to, and fraOptions lets you know that you're dealing with a Frame control that has something to do with Options.

Since the inception of Visual Basic, common usage has resulted in a widely-accepted collection of control name prefixes. If you use these prefixes, there will never be any confusion as to exactly what type of controls you're using.

There are literally thousands of ActiveX controls available. Obviously, somewhere along the line, you'll either have to use the same three-letter prefix for two different types of controls, or, apply a longer (or shorter) prefix to distinguish between them.

Table C.1 lists some typical prefixes suggested by Microsoft.

Table C.1 Typical ActiveX Control Prefixes

Variables and Constants

Like controls, variables should also be given prefixes that identify their type. In addition to documenting a variable's type, you should consider adding an additional prefix to describe its scope if it's not a global variable. Microsoft suggests prefixing a variable name with an s if it's a Script-level variable. Thus, using the suggested prefix from Table C.1 for a Script-level Integer variable, a typical example would be sintUserID.

Remember, these prefixes are strictly for the benefit of people (including you, of course) who read the codeùgiving a String a prefix of "byt" will not change it into a Byte!

Functions (in addition to executing code) return values. Therefore, you should also use these prefixes in your Function declarations.

Table C.2 contains the variable type prefixes Microsoft recommends.

Table C.2 Variable Name Prefixes

Procedures

Procedure names, like variable names, should be given descriptive names. Functions, like variables, should be given a type prefix according to the examples in Table C.2, because they return a value; Sub procedures, on the other hand, don't return any value, and therefore require no prefix.

Loops, Blocks, and White Space

Just as judicious use of white space makes text easier to read, a well-formatted code listing is easy to understand at a glance. When loops and other structures are properly indented, it's immediately apparent how the program is intended to flow. It's much easier to debug a program where each nested If/Then is indented a few spaces more than the preceding level. Placing all code flush left may be a little easier when you first type it in, but doing so guarantees you a maintenance nightmare.

If you simply indent each level of a loop and block by three or four spaces, you'll do well.

Here's how some typical code should look:

Sub CheckOrder

For intC = intStart to intFinish

If intRequired(intC) <= intOnHand Then

Select Case intOnHand

Case intReorderLevel

GeneratePO

ProcessOrder

Case Is < intReorderLevel

ProcessOrder

End Select

Else

NotifyReceiving

EndIf

Next

End Sub

Compare the preceding section of code with the following, and see which you would rather work with:

Sub CheckOrder

For intC = intStart to intFinish

If intRequired(intC) <= intOnHand Then

Select Case intOnHand

Case intReorderLevel

GeneratePO

ProcessOrder

Case Is < intReorderLevel

ProcessOrder

End Select

Else

NotifyReceiving

EndIf

Next

End Sub

In addition to using white space for indentation within a block of code, major sections of code (i.e., scripts, and major sections within scripts)should also have a blank line between them, to visually separate them.

Comments

It's important to comment every significant thing your program does and contains. Put blocks of indented comments at the start of every procedure (and every major section within a procedure), describing the purpose of the code that follows and providing meaningful information about how it accomplishes its task. Describe which variables it uses, which ones it modifies, and which it returns.

You should also place in-line comments at the end of significant lines of code, explaining what's being done.

HTML Considerations

As this book goes to press, recommended placement for scripts within HTML pages is uncertain. Some sources within Microsoft suggest placing them within the <HEAD> section, and others recommend putting them at the end of the <BODY> section. This is largely a style consideration, inasmuch as execution is unaffected by placement.

Regardless of where you put them, you should consider surrounding your scripts in HTML Comment tags (<!--...-->) to prevent them from appearing as text when viewed by non-ActiveX-enabled browsers.

Also, even though they won't actually do anything in browsers that don't support ActiveX, HTML controls will be visible in them if you place them within <FORM> blocks.